;+
; NAME:
;       WEIGHT_PROB
;
; PURPOSE:
;       De-weights a probability vector by making it closer to a
;       uniform probability without sacrificing the shape and relative
;       amplitudes of the probability peaks.
;
; CATEGORY:
;       BGPS distance-omnibus probability utility
;
; CALLING SEQUENCE:
;       new_prob = weight_prob( old_prob, weight [,/VERBOSE])
;
; INPUTS:
;       old_prob  -- Original, unweighted probability from the prob_*
;                    routines
;       weight    -- Weight (in range [0,1]) to be assigned to this
;                    probability.  A weight of 0 results in a uniform
;                    probability being returned.
;
; OPTIONAL INPUTS:
;       NONE
;
; KEYWORD PARAMETERS:
;       VERBOSE   -- verbose output
;
; OUTPUTS:
;       new_prob  -- New, weighted probability
;
; OPTIONAL OUTPUTS:
;       NONE
;
; EXAMPLE:
;       pvec.lonlat = weight_prob(pvec.lonlat, 0.5, /VERBOSE)
;
; MODIFICATION HISTORY:
;
;       Created:  06/22/10, TPEB -- Initial version.
;       Modified: 02/27/12, TPEB -- Error handling cleanup.
;       Modified: 03/01/12, TPEB -- Internally deals with input PVEC
;                                   that is not normalized to unity
;                                   total probability (previous
;                                   implicit assumption).
;
;-

FUNCTION WEIGHT_PROB, pvec, weight, VERBOSE=verbose
  
  COMPILE_OPT OBSOLETE
  
  ;; Error checking
  IF (weight LT 0.d) OR (weight GT 1.d) THEN BEGIN
     message,'Weight outside limits (must be [0,1])',/cont
     RETURN,pvec
  ENDIF
  
  ;; Measure original normalization, then normalize input
  norm = TOTAL(pvec)
  nprob = pvec / norm
  
  ;; Create uniform probability vector for 'dilution'
  uniform = dblarr(n_elements(nprob)) + 1.d/n_elements(nprob)
  
  ;; Create weighted probability
  new_prob = TEMPORARY(nprob) * double(weight) + $
             TEMPORARY(uniform) * (1.d - double(weight))
  
  RETURN,new_prob * norm
  
END
